//
//  NSString+Extensions.h
//  NXLib
//
//  Created by AK on 14-3-27.
//  Copyright (c) 2014年 AK. All rights reserved.
//

#import <Foundation/Foundation.h>

@interface NSString (NXCategory)

+ (NSString *)stringToSha1:(NSString *)str;
/**
 + (NSString*)stringTruncatedToWidth:withString:andFont:
 Generates a truncated copy of the given NSString, truncated to the desired
 width for the given typeface and size.
 
 width - A CGFloat representing the desired width of the truncated NSString.
 string - An NSString object with the content to be truncated.
 font - A UIFont object representing the desired typeface and font size.
 
 Example:
 NSString *message = @"Can you hear this long-winded message?";
 UIFont *messageFont = [UIFont fontWithName:@"Marker Felt" size:32];
 NSString *output = [NSString stringTruncatedToWidth:48.0f
 withString:message
 andFont:messageFont];
 
 Returns an NSString containing the truncated string, followed by an ellipsis.
 */
+ (NSString *)stringTruncatedToWidth:(CGFloat)width withString:(NSString*)string andFont:(UIFont*)font;
 /**
 + (BOOL)stringIsPalindrome:
 Deterines if a provided NSString is a palindrome.
 
 aString - The NSString to be tested.
 
 Example:
 [NSString stringIsPalindrome:@"RADAR"]; // return YES
 
 Returns a BOOL cooresponding to the NSString palindrome status.
 */
+ (BOOL)stringIsPalindrome:(NSString*)aString;


/**
 - (NSString*)MD5Hash
 Generates an MD5 cryptographic hash of this NSString's contents
 
 Example:
 NSString *hash = [@"The quick brown fox jumped over the lazy dog" MD5Hash];
 
 Returns an NSString containing the hexidecimal representation of the MD5 hash.
 */
- (NSString*)MD5Hash;


/**
 - (NSString*)truncateToWidth:withFont:
 Generates an NSString truncated to the indicated width
 for a given a typeface and size.
 
 width - A CGFloat representing the desired width of the truncated NSString.
 font - A UIFont object representing the desired typeface and font size.
 
 Example:
 NSString *testString = @"This string is too damn long!"
 [testString truncateToWidth:64.0f
 withFont:[UIFont fontWithName:@"Helvetica"
 size:28]];
 
 Returns an NSString containing the truncated string, followed by an ellipsis.
 */
- (NSString*)truncateToWidth:(CGFloat)width withFont:(UIFont*)font;


/**
 - (BOOL)isPalindrome
 Determines whether this string is a palindrome.
 
 Example:
 [@"HANNAH" isPalindrome]; // returns YES
 [@"CLAUDE" isPalindrome]; // returns NO
 
 Returns a BOOL corresponding to this NSString's palindrome status.
 */
- (BOOL)isPalindrome;

/**
 -(NSString*)reverse
 Reverses the contents of this NSString.
 
 Example:
 NSString *testString = @"stressed";
 NSString *testReversed = [testString reverse]; // @"desserts"
 
 Returns an NSString with the original NSString's contents reversed
 */
- (NSString*)reverse;


/**-------------------------------------------------------------------------------------
 @name Formatting File Sizes
 ---------------------------------------------------------------------------------------
 */


/** Formats the passed number as a byte value in a form that is pleasing to the user when displayed next to a progress bar.
 
 Output numbers are rounded to one decimal place. Bytes are not abbreviated because most users might not be used to B for that. Higher units are kB, MB, GB and TB.
 
 @param bytes The value of the bytes to be formatted
 @return Returns the formatted string.
 
 */
+ (NSString *)stringByFormattingBytes:(long long)bytes;

- (NSNumber *)stringToNSNumber;

- (BOOL)isEmpty;

- (BOOL)stringContainsSubString:(NSString *)subString;

- (NSString *)stringByReplacingStringsFromDictionary:(NSDictionary *)dict;

/**-------------------------------------------------------------------------------------
 @name Working with Identifiers
 ---------------------------------------------------------------------------------------
 */

/** Creates a new string that contains a generated UUID.
 
 @return The path to the app's Caches folder.
 */
+ (NSString *)stringWithUUID;


/**-------------------------------------------------------------------------------------
 @name Working with Checksums
 ---------------------------------------------------------------------------------------
 */

/** creates an MD5 checksum
 
 @return returns an MD5 hash for the receiver.
 */
- (NSString *)md5Checksum;

/**-------------------------------------------------------------------------------------
 @name Getting Standard Paths
 ---------------------------------------------------------------------------------------
 */

/** Determines the path to the Library/Caches folder in the current application's sandbox.
 
 The return value is cached on the first call.
 
 @return The path to the app's Caches folder.
 */
+ (NSString *)cachesPath;


/** Determines the path to the Documents folder in the current application's sandbox.
 
 The return value is cached on the first call.
 
 @return The path to the app's Documents folder.
 */
+ (NSString *)documentsPath;

/**-------------------------------------------------------------------------------------
 @name Getting Temporary Paths
 ---------------------------------------------------------------------------------------
 */

/** Determines the path for temporary files in the current application's sandbox.
 
 The return value is cached on the first call. This value is different in Simulator than on the actual device. In Simulator you get a reference to /tmp wheras on iOS devices it is a special folder inside the application folder.
 
 @return The path to the app's folder for temporary files.
 */
+ (NSString *)temporaryPath;


/** Creates a unique filename that can be used for one temporary file or folder.
 
 The returned string is different on every call. It is created by combining the result from temporaryPath with a unique UUID.
 
 @return The generated temporary path.
 */
+ (NSString *)pathForTemporaryFile;


/**-------------------------------------------------------------------------------------
 @name Working with Paths
 ---------------------------------------------------------------------------------------
 */

/** Appends or Increments a sequence number in brackets
 
 If the receiver already has a number suffix then it is incremented. If not then (1) is added.
 
 @return The incremented path
 */
- (NSString *)pathByIncrementingSequenceNumber;


/** Removes a sequence number in brackets
 
 If the receiver number suffix then it is removed. If not the receiver is returned.
 
 @return The modified path
 */
- (NSString *)pathByDeletingSequenceNumber;

/**-------------------------------------------------------------------------------------
 @name Encoding Strings for URLs
 ---------------------------------------------------------------------------------------
 */


/** Encoding suitable for use in URLs.
 
 stringByAddingPercentEscapes does not replace serveral characters which are problematics in URLs.
 
 @return The encoded version of the receiver.
 */
- (NSString *)stringByURLEncoding;

/**-------------------------------------------------------------------------------------
 @name Working with UTIs
 ---------------------------------------------------------------------------------------
 */

/**
 Method to get the recommended MIME-Type for the given file extension. If no MIME-Type can be determined then 'application/octet-stream' is returned.
 @param extension the file extension
 @return the recommended MIME-Type for the given path extension.
 */
+ (NSString *)MIMETypeForFileExtension:(NSString *)extension;


/**
 Method to get the official description for a given file extension.
 @param extension the file extension
 @return the description
 */
+ (NSString *)fileTypeDescriptionForFileExtension:(NSString *)extension;


/**
 Method to get the preferred UTI for a given file extension.
 @param extension the file extension
 @return the UTI
 */
+ (NSString *)universalTypeIdentifierForFileExtension:(NSString *)extension;

/**
 Get the prefered file extension for a given UTI.
 @param UTI he UTI
 @returns The File Extension
 */
+ (NSString *)fileExtensionForUniversalTypeIdentifier:(NSString *)UTI;

/**
 Tests if the receiver conforms to a given UTI.
 @param conformingUTI the UTI that is tested against
 @return `YES` if the receiver conforms
 */
- (BOOL)conformsToUniversalTypeIdentifier:(NSString *)conformingUTI;

/**
 @returns `YES` if the receiver is a movie file name
 */
- (BOOL)isMovieFileName;

/**
 @Returns `YES` if the receiver is an audio file name
 */
- (BOOL)isAudioFileName;

/**
 @Returns `YES` if the receiver is an image file name
 */
- (BOOL)isImageFileName;

/**
 @Returns `YES` if the receiver is an HTML file name
 */
- (BOOL)isHTMLFileName;

@end
